Here are some notes on the applications and tools in this folder, as well as some
additional notes about the slot manager in general:


1.  CRCPATCH

The crcpatch tool calculates the crc value.  See the example build sequence below for 
the invocation sequence.  It is run after the declaration ROM file has been assembled 
and linked.

The crcpatch tool calculates the crc value using this algorithm:

Start pointer at bottom of ROM (top of ROM - length)
Initialize sum to 0 (sum will be the CRC value)
@1 	Rotate sum left by one bit (with ROL.L #1 instruction)
 		 If pointer is pointing to CRC field in format header, goto @2 (i.e. don't count CRC field)
   	Get a byte
   	Add byte to sum
@2 	Increment pointer to next data byte
Goto @1 until done


2.  DATA TOOL

The data tool strips off the code 0 segment, and puts the code 1 segment in a data 
file, so the data file can be downloaded to a rom burner.


3.  TJSCOMM APPLICATION

The tjscomm application is a rudimentary data comm program.  It can be used to download 
data file to a ROM burner.


4.  GETSINFO APPLICATION

The GetsInfo application prints out some summary info for cards in certain slots.  Don't 
worry about the slot 0 error, as future Macintosh II ROMs will contain a slot 0
sResource.


5.  SLOTMGRTEST APPLICATION

The SlotMgrTst application exercises the slot manager.  It runs continuously, and the only way 
to stop it is to bring down and hold down a menu.  It has limited usefullness but is included 
anyway.


6.  BUILDING A CONFIG ROM USING THE TOOLS

Here is an example of how the Apple Video ROM Code was built:


## Assemble and link the ROM
directory "{Decl}TFB-b1:"
asm -wb -i {AIncludes}nFiles  -i {Decl} VideoROM.a
Link VideoROM.a.o   -o videoROM

### Patch the crc value and then convert the code to a data file.
### in this case, operate on the linked declaration file (videoROM)
Tools:crcPatch" videoROM
Tools:Data" videoROM  tfbROM1.d


7.  MBGETSINFO APPLICATION

The GetSInfo application used a preliminary (Beta) slot manager interface that changed radically 
when the Macintosh II went into final production.  mbgetsinfo is a very preliminary sampe that uses
the real slot manager interface.  It checks the slots, and displays a partial summary of what is in 
the slots.  It doesn't go as far as getting to the vendor info, that is something I'll fix up later.  
It will show you how to use the slot manager, though.  Once you see how this program gets to data
structures, you can extend it to the rest of the slot manager.

The user interface is hideous, of course.  It uses writelns, doesn't update, etc.  I'd shoot myself 
if I tried to ship this, but right now, it is an in house experiment only.  I'll make it a real
Macintosh application yet!



8.  GENERAL SLOT MANAGER DECLARATION ROM DISCUSSION

{semi-standard slot manager canned answer follows and may be disregarded if you are familier 
with the slot manager}



Functional sResources are recommended in addition to the board sResource, and exist to 
tell the world what type of function(s) your board can perform.  There is usually one 
of these functional sResources for each function the board can perform.  Conceptually, each 
sResource tells the world one function the card can perform.  The board sResource is sort 
of a degenerate case of sResources: it exists to tell the slot manager that it can 
perform the function of being a board (and it provides a handy place to store board 
related data).  The board sResource which has a functional sRsrc_Type of:

CatBoard         EQU  $0001  ;always 1 for board sResource
TypBoard         EQU  $0000  ;always 0 for board sResource
DrSwBoard        EQU  $0000  ;always 0 for board sResource
DrHwBoard        EQU  $0000  ;always 0 for board sResource


A board resource is required if the slot manager is to be used at all, since if there 
is no board resource, the slot manager will mark the slot as empty, and no slot manager
calls to that slot will work.  

With this scheme, therefore, a multifunction card would have the board sResource, plus a 
functional sResource for each function the board could perform.  as an example, if you had a 
multifunction board that was a display card, a modem, a parallel i/o, and a SCSI card, you'd 
have five sResources:

  the board sResource (as stated above boards should always have this)

  an sResource with an sRsrc_Type that has something like CatDisplay,
  TypVideo, etc.

  an sResource with an sRsrc_Type that has something like CatCommunication,
  TypModem, etc.

  an sResource with an sRsrc_Type that has something like CatCommunication,
  TypParallel, etc.

  an sResource with an sRsrc_Type that has something like CatIntBus,
  TypSCSI, etc.
  
MacDTS issues functional sResources equates for now; eventually you'll find standard Category, Type
and SW ids in the MPW equates.  You will always need to have DTS assign you a unique DrHw equate
since that is what differentiates unique hardware (i.e. boards), and you may need to have DTS assign
a drSw equate if you have a unique driver interface that isn't in the equates (the most common 
example of this is developers who make video boards compatible with the Apple video driver 
interface - The CatDisplay, TypVideo, Category and Type have already been defined, as well as the
Apple video driver interface, which is represented by the DrSwApple equate.  All a developer would
need then would be a unique DrHw equate.   

Your application will then look for your board by basically calling SNextTypesRsrc after 
filling in the spCategory, spCType, spDrvrSW, spDrvrHW fields calling for your functional 
sRsrc_Type fields (see below for an example of how QuickDraw might look for an example).

There is an spTBMask field in the same SNextTypesRsrc call that allows you to mask off 
any of these values (making them a don't care).  This is useful if you have a driver that 
will take care of the underlying hardware, so you don't have to worry about particular hardware 
revisions.  Most cards that have drivers on board will allow the app to mask off the spDrvrHW 
field so the application will work with different revisions of the board.  Of course this 
means less maintainence for the application programmer, and a much higher customer 
satisfaction level, since their application won't cease to work if they buy a later 
version of your board.  It allows you to rev your driver by sending the customer a new 
ROM or init file without having the customer get a new version of the application.

Additionally, if you define a driver interface for your board (like Apple did with the 
video driver), then other manufacturers can make applications that will find your board 
by calling SNextTypesRsrc with the hw id again masked off, because they know your driver 
will handle the underlying hardware, no matter what it is.   This should sell more of your 
boards by providing more applications for the board.  Conversely, if you define a software 
interface, other manufacturers can make compatible boards that your application will run 
on.  This is exactly what Apple did by defining the video driver interface for QuickDraw.  All 
QuickDraw does is call SNextTypesRsrc with the following sRsrc_Type fields, i.e.

  spCategory := catDisplay;
  spCType := typVideo;
  spDrvrSW := drSwApple;

again, masking off the spDrvrHW field.

Thus when QuickDraw makes the call it finds out all the compatible video boards which may 
have been made by Apple, SuperMac, E-machines, etc.  All these boards have different hardware 
but the individual drivers take care of everything.  This allows the customer to choose among 
various boards for his/her system.

In summary, you want a configuation ROM with a board sResource and the functional sResource 
listed above.  Ideally, you want a driver in ROM as well, but you could have your app carry 
the driver or interface software inside the app.  This locks a particular app to a particular 
rev of a board, and provides you the manufacturer with headaches shoudl you decide to rev or 
change your board such that the app no longer works.  Then you might have to maintain different 
versions of your app since your customers might have either version of your board.   Anything 
that inconveniences the customer will almost certainly (and I am really serious here) subject 
you to abuse and severe criticism from anyone who reviews your product.


9. HOW TO GET BOARD IDS AND SRESOURCE IDS

When a developer wishes to get board ids and/or functional sRsrc_Type values (Category, 
cType, DrvrSw and DrvrHw values), then the developer needs to contact us here at MacDTS 
with the following info:

- What the board will do (so we can assign the values)
- the official product name for the board (or a code name)
- whether or not the board will have a software driver other than one
  which has been pre-defined (like Apple's video driver).
- whether or not the board will have driver that will be on board 
  (that is, in the ROM), or whether or not it will be a driver that
  gets installed at init time, in the application, etc.
- the company address (mailing and electronic mail addresses if possible) and the
  name of the person in the company responsible for the board.

We then assign the values for Category, cType, DrvrSw and DrvrHw ids.

We need the above information because we are maintaining a database to prevent id 
conflicts.  We don't give the database out because it will have unannounced products 
on it.  You can be assured we keep all information confidential.
